\pard\tx3120\tx3620\tx4120\fs28\li2620 ResultObject derives, logically, from the now obsolete classes ErrorInfo and Reply. The goal of those two classes was to provide a standard, and hopefully frequently used, way to get the results of a method call back to the caller. In the case of ErrorInfo, this meant to get error codes and descriptive error strings returned. Reply was a sublcass of ErrorInfo, and thus provided the previously mentioned error code returns, plus ways to get data returned as well. The idea behind them was that objects would return, say, a Reply object with complete error information as well as any data the caller had requested. This made it easier for an object to provde needed data as well as error information without relying on things like external global variables for error codes, or what have you. Put another way, one could now
\i always
\i0 provide error codes when returning data without any additional work, thus potentially providing more information to the caller. Being objects, there was also room to subclass them and provide even more specialized and detailed error codes, or to return multiple pieces of non error-related data at once. These class proved, however, to be more cumbersome than they were worth. In all too many of the cases where one was returned, the programmer didn't want to deal with checking the error code. This resulted in cumbersome effortrts to dispose of the result object as soon as it was returned. Thus, in a majority of the cases, an object was created, initalized, filled, returned, and then deallocated, without even referencing any of the information in the returned object. The result was undoubtedly slower code that was considerably harder to read.\
\fs16 \
\fs28 The ResultObject class seeks to provide the same services that Reply did, without its cumbersome aspects. Rather than having new classes return a Reply or ErrorInfo object, the class tree is set up so that new classes decend from ResultObject rather than Object. ResultObject provides the internal storage to remember error information for the last method called, as well as storage of data. Classes decended from ResultObject can behave normally, and return self or a single data result. Additionally, methods can store error information, and additional data in the object, and allow the caller to retrieve it at its conveniance.\
\fs16 \
\fs28 ResultObject allows one to store an error code and a textual error string, as well as several pieces of data (up to five, presently) that might be requested by a caller. It recognizes only 7 data types presently: Character, Cstring,
\pard\tx3120\tx3620\tx4120\li2620 , PositiveInteger, Object, Pointer and Boolean. Support for ByteString, float types, and others may (or may not) be forthcomming. It also provides one standard error code: ERR_OK, which corresponds to the number 0, and should always be used when no notable errors or problems occured.\
\fs16 \
\fs28 ResultObject has a large set of straightforward methods to set and retrieve result data, as well as error information. See descriptions below for specific details.\
\fs16 \
\fs28 The methods can be divided into two groups: those that store data, and those that retrieve it. The methods that store data should be called only by the class decended from ResultObject. These methods allow one to store an error code and an error string, as well as store items of particular data types (e.g. a method to store an Integer). There are two sub-sets of methods for storing the data. One set, the
\b Store…
\b0 methods, implicitly store their data in the first storage area. The
\b Put…:Into:
\b0 methods store their data into any of the storage areas. Additionally, there is one method that clears all waiting stored data.\
\fs16 \
\fs28 The methods to retrieving data are much the same as the storage ones. There is a method to retrieve an error code, and one to retrieve the error string. There are a set of Get… methods that always retrieve the data item in the first slot, and a set og Get…From: methods to retrieve from arbitrary return positions.\
\fs16 \
\fs28 One can check if an error occurred when storing or retrieving a data value by using the
\b Store
\b0 and
\b Get
\b0
\b MyError
\b0 methods.\
\fs16 \
\fs28 Note that when passed an Integer, Character, PositiveInteger, or Boolean, the object will always make a copy of the data internally, and copies will always be returned. Objects are always stored and returned as pointers; their data is not copied. For Cstrings, error strings, and Pointers, the default
\b Store…
\b0 methods will store only references, but there are
\b Copy…
\b0 methods provided which will copy the referenced data (Note: if the pointer points to a block that in turn points to other blocks of memory, those secondary blocks will not be copied). When retrieved, Pointers are always returned merely as poiners, not as copies of the data the poiners point to, while CStrings and error strings are always copied before being returned. \
\fs16 \
\fs28 If an illegal storage area reference is given with a Put method, the data will be ignored, and no errors will be generated. If one tries to retrieve a data type that isn't in a storage area, or to request data from a storage area that doesn't exist, you'll get a null value returned; the error codes will be modified to reflect this.\
\fs16 \
\pard\tx7140\li2100 \
\
\fs28 INSTANCE VARIABLES\
\fs16 \
\pard\tx6640\tx9660\tx10180\i\fs28\fi-4040\li6640 Inherited from Object
\fs28 ResultVals Used to store all data values to be returned, as well as the internal error code, and the error code and text the subclassing object is returning.
\fs16 \
\pard\tx7140\li2100 \
\
\
\fs28 METHOD TYPES\
\fs16 \
\pard\tx7140\tx10180\tx10680\fs28\fi-4540\li7140 Creating/Initializing, and Freeing
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 This makes a copy of the specified pointer's data, and stores a reference to the copy in the storage area referenced by
\i reference
\i0 . This is in contrast to
\b StorePointer:
\b0 which only stores a reference to the data. Returns self.\
\pard\tx7140\fs16\li2100 \
\b \
\fs28 init\
\pard\b0\fi-1020\li3620 - (Object)
\b init\
\fs16 \
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Unsurprisingly, this initalizes a ResultObject object. It clears the internal variables to default values, and returns self (all this after having initalized its parent, of course). \
\pard\tx7140\fs16\li2100 \
\b \
\fs28 free\
\pard\b0\fi-1020\li3620 -
\b free\
\fs16 \
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Disposes of the instance values, freeing those it owns, and then frees the object.\
\fs16 \
\pard\tx7140\b\li2100 \
\fs28 GetBoolean\
\pard\f5\b0\fi-1020\li3620 -
\f4 (Boolean)
\b GetBoolean\
\fs16 \
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the Boolean in the first storage area.\
\fs16 \
\pard\tx7140\b\li2100 \
\fs28 GetBooleanFrom:\
\pard\f5\b0\fi-1020\li3620 -
\f4 (Boolean)
\b GetBooleanFrom:
\b0 (Integer)
\i reference
\b\i0 \
\fs16 \
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the Boolean in the storage area specified by reference (use the defined constants from below).\
\fs16 \
\pard\tx7140\b\li2100 \
\fs28 GetCharacter\
\pard\f5\b0\fi-1020\li3620 -
\f4 (Character)
\b GetCharacter\
\fs16 \
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the character in the first storage area.\
\fs16 \
\pard\tx7140\b\li2100 \
\fs28 GetCharacterFrom:\
\pard\f5\b0\fi-1020\li3620 -
\f4 (Character)
\b GetCharacterFrom:
\b0 (Integer)
\i reference
\b\i0 \
\fs16 \
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the character in the storage area specified by reference (use the defined constants from below).\
\fs16 \
\pard\tx7140\b\li2100 \
\fs28 GetCString\
\pard\f5\b0\fi-1020\li3620 -
\f4 (CString)
\b GetCString\
\fs16 \
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the character in the first storage area.\
\fs16 \
\pard\tx7140\b\li2100 \
\fs28 GetCStringFrom:\
\pard\f5\b0\fi-1020\li3620 -
\f4 (GetCString)
\b GetCStringFrom:
\b0 (Integer)
\i reference
\b\i0 \
\fs16 \
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the Cstring in the storage area specified by reference (use the defined constants from below).\
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Retrieves a data item of type theType from the storage pointed to by reference. Return the type as a generic type. If there is an error, store an error code via
\b StoreMyError:.
\b0 \
\fs16 \
\pard\tx7140\b\li2100 \
\fs28 GetErrorCode\
\pard\f5\b0\fi-1020\li3620 -
\f4 (Integer)
\b GetErrorCode\
\fs16 \
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the error code that the object is currently storing\
\fs16 \
\pard\tx7140\b\li2100 \
\fs28 GetErrorText\
\pard\f5\b0\fi-1020\li3620 -
\f4 (CString)
\b GetErrorText\
\fs16 \
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the Cstring in the error text storage area. Note that this is a full
\i copy
\i0 of the string. One can not obtain a mere reference to it. One is responsibe for freeing the text using the usual
\b free
\b0 () call.\
\fs16 \
\pard\tx7140\b\li2100 \
\fs28 GetInteger\
\pard\f5\b0\fi-1020\li3620 -
\f4 (Integer)
\b GetInteger\
\fs16 \
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the Integer in the first storage area.\
\fs16 \
\pard\tx7140\b\li2100 \
\fs28 GetIntegerFrom:\
\pard\f5\b0\fi-1020\li3620 -
\f4 (Integer)
\b GetIntegerFrom:
\b0 (Integer)
\i reference
\b\i0 \
\fs16 \
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the Integer in the storage area specified by reference (use the defined constants from below).\
\fs16 \
\pard\tx7140\b\li2100 \
\fs28 GetMyError\
\pard\f5\b0\fi-1020\li3620 -
\f4 (Integer)
\b GetMyError\
\fs16 \
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Returns a copy of the error code that was stored while last setting or getting a result.
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Stores a copy of the Boolean in the storage area specified by reference (use the defined constants from below). Returns self.\
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Store a copy of the character in the storage area specified by reference (use the defined constants from below). Returns self.\
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Stores the specified data with the specified type into the specified storage area (and indicate whether we are just pointing tothe data, or if we have our own copy), if possible. If it has trouble, an error is stored via StoreMyError:. Returns self.
\pard\tx7140\b\li2100\fc0 \
\pard\tx3120\tx3620\tx4120\b0\fs16\li2620 \
\pard\tx7140\b\li2100 \
\fs28\fc0 Put
Integer
:Into:
\
\pard\f5\b0\fi-1020\li3620 -
\f4 (Object)
\pard\tx533\tx1067\tx1601\tx2135\tx2668\tx3202\tx3736\tx4270\tx4803\tx5337\b\fc0 Put
\pard\tx3120\tx3620\tx4120\b0\fs28\li2620 Stores a copy of the Integer in the storage area specified by reference (use the defined constants from below). Returns self.\
\pard\tx3120\tx3620\tx4120\fs28\li2620 There is no way provided to make an actual copy of an object, rather than just copy a reference.\
Dealing with its own errors has not been examined closely, and they may be incomplete.\
We are also happy and content to just overwrite any data items already there. (this may be a feature)
\pard\tx7140\fs16\li2100 \
\
\fs28 ENHANCEMENT IDEAS\
\fs16 \
\pard\tx3120\tx3620\tx4120\fs28\li2620 Everything should be collapsed into object types!\
The distinction between copying the actual data, and only copying a reference seems a bit cumbersome, and some way to flatten this should be provided eventually.\
Perhaps add a set of
\b Store…
\b0 methods that would automatically store in the next available storage area?\
Make the storage area set a dynamically sized linked list, so that one needn't worry about running out of storage areas\
\fs16 \
\pard\tx7140\li2100 \
\fs28 CONSTANTS AND DEFINED TYPES\
\fs16 \
\pard\tx6480\tx7180\fs24\li2620 /* Types used by ResultObjects */\
